home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-02 / tphrt3.zip / TPHRTV3.DOC < prev    next >
Text File  |  1990-07-23  |  77KB  |  2,176 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.                                      TPHRT
  22.  
  23.  
  24.  
  25.                    Turbo Pascal High Resolution Timer Toolbox 
  26.  
  27.  
  28.  
  29.                                   Version 3.00
  30.  
  31.  
  32.  
  33.                           Shareware Evaluation Version
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.                                   Ryle Design
  49.  
  50.                                   P.O. Box 22
  51.  
  52.                           Mt. Pleasant, Michigan 48804
  53.  
  54.                                 (517) 773-0587
  55.  
  56.                                Cserv 73047,1765
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.  
  74.  
  75.                                  Contents
  76.  
  77.  
  78.  
  79.           TPHRT User Guide                                           1
  80.              Introduction  . . . . . . . . . . . . . . . . . . . . . 1
  81.              Functional Overview . . . . . . . . . . . . . . . . . . 2
  82.              Theory  . . . . . . . . . . . . . . . . . . . . . . . . 3
  83.              TPHRT Function Descriptions . . . . . . . . . . . . . . 4
  84.              Examples  . . . . . . . . . . . . . . . . . . . . . . . 8
  85.              Technical Support . . . . . . . . . . . . . . . . . . . 8
  86.              Shareware . . . . . . . . . . . . . . . . . . . . . . . 8
  87.  
  88.           TPHRT Function Reference                                  11
  89.              t_ask_delay . . . . . . . . . . . . . . . . . . . . .  11
  90.              t_ask_timer . . . . . . . . . . . . . . . . . . . . .  11
  91.              t_bios_ask  . . . . . . . . . . . . . . . . . . . . .  12
  92.              t_bios_entry  . . . . . . . . . . . . . . . . . . . .  12
  93.              t_bios_exit . . . . . . . . . . . . . . . . . . . . .  13
  94.              t_bios_fname  . . . . . . . . . . . . . . . . . . . .  13
  95.              t_bios_load_desc  . . . . . . . . . . . . . . . . . .  13
  96.              t_bios_report . . . . . . . . . . . . . . . . . . . .  14
  97.              t_bios_resume . . . . . . . . . . . . . . . . . . . .  14
  98.              t_bios_reset  . . . . . . . . . . . . . . . . . . . .  15
  99.              t_bios_rname  . . . . . . . . . . . . . . . . . . . .  15
  100.              t_bios_set_file . . . . . . . . . . . . . . . . . . .  15
  101.              t_bios_set_user . . . . . . . . . . . . . . . . . . .  16
  102.              t_bios_start  . . . . . . . . . . . . . . . . . . . .  16
  103.              t_bios_stop . . . . . . . . . . . . . . . . . . . . .  17
  104.              t_bios_suspend  . . . . . . . . . . . . . . . . . . .  18
  105.              t_calc_delay_ff . . . . . . . . . . . . . . . . . . .  18
  106.              t_calib . . . . . . . . . . . . . . . . . . . . . . .  18
  107.              t_cvt_time  . . . . . . . . . . . . . . . . . . . . .  19
  108.              t_delay_calib . . . . . . . . . . . . . . . . . . . .  19
  109.              t_diff  . . . . . . . . . . . . . . . . . . . . . . .  20
  110.              t_do_delay  . . . . . . . . . . . . . . . . . . . . .  20
  111.              t_do_delay_wints  . . . . . . . . . . . . . . . . . .  20
  112.              t_entry . . . . . . . . . . . . . . . . . . . . . . .  21
  113.              t_exit  . . . . . . . . . . . . . . . . . . . . . . .  21
  114.              t_fname . . . . . . . . . . . . . . . . . . . . . . .  22
  115.              t_get . . . . . . . . . . . . . . . . . . . . . . . .  22
  116.              t_get_delay_ff  . . . . . . . . . . . . . . . . . . .  22
  117.              t_hires_entry . . . . . . . . . . . . . . . . . . . .  23
  118.              t_hires_exit  . . . . . . . . . . . . . . . . . . . .  23
  119.              t_hook_int  . . . . . . . . . . . . . . . . . . . . .  23
  120.              t_min_delay . . . . . . . . . . . . . . . . . . . . .  24
  121.              t_name  . . . . . . . . . . . . . . . . . . . . . . .  24
  122.              t_report  . . . . . . . . . . . . . . . . . . . . . .  24
  123.              t_request . . . . . . . . . . . . . . . . . . . . . .  25
  124.              t_res_delay . . . . . . . . . . . . . . . . . . . . .  25
  125.              t_reset . . . . . . . . . . . . . . . . . . . . . . .  25
  126.  
  127.  
  128.  
  129.                                        i
  130.  
  131.  
  132.  
  133.  
  134.  
  135.              t_resume  . . . . . . . . . . . . . . . . . . . . . .  26
  136.              t_rname . . . . . . . . . . . . . . . . . . . . . . .  26
  137.              t_set_delay_ff  . . . . . . . . . . . . . . . . . . .  26
  138.              t_setmode . . . . . . . . . . . . . . . . . . . . . .  27
  139.              t_start . . . . . . . . . . . . . . . . . . . . . . .  27
  140.              t_stop  . . . . . . . . . . . . . . . . . . . . . . .  28
  141.              t_suspend . . . . . . . . . . . . . . . . . . . . . .  28
  142.              t_unhook_int  . . . . . . . . . . . . . . . . . . . .  28
  143.  
  144.           TPHRT V3.00 Registration . . . . . . . . . . . . . . . .  30
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                        ii
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.                                 TPHRT User Guide
  206.  
  207.  
  208.      Introduction
  209.  
  210.  
  211.      TPHRT (Turbo Pascal High Resolution  Timer) is a software library that
  212.      provides the software developer with  reliable  timing  functions that
  213.      work across  the entire Intel 80xxx PC compatible hardware environment
  214.      with microsecond resolution. The TPHRT timing logic  calibrates itself
  215.      to the host PC clock rate and processor environment at run-time,  so a
  216.      single executable program will yield  accurate  results  regardless of
  217.      the host microprocessor and clock speed.
  218.  
  219.      TPHRT  is  the  definitive choice for any PC application that requires
  220.      precision timing.  Some typical TPHRT applications are:
  221.  
  222.      Source Code Timer/Profiler
  223.      By  adding timer calls to source code  under  development,  TPHRT  can
  224.      generate a detailed summary  of  execution  time by program subroutine
  225.      and immediately  illustrate  the  software's  "hot  spots"  that might
  226.      benefit from further code or algorithm optimization.  Unlike "binning"
  227.      profilers  that display the number of "hits" in  a  range  of  program
  228.      addresses, TPHRT provides  a  direct one to one correspondence between
  229.      source code and elapsed time with user defined granularity.
  230.  
  231.      Hardware Performance Evaluator
  232.      The high resolution and  self  calibration  features  of TPHRT make it
  233.      ideal  for  insertion  in code to evaluate hardware performance.  Disk
  234.      drives,  numeric processors and CRT controllers  can  all  have  their
  235.      throughput measured very  accurately  with  TPHRT,  and  with numerous
  236.      timers  at  the  users   disposal,   many   device  functions  may  be
  237.      independently  measured  in  a single run.  The formatted timer report
  238.      generated  by  TPHRT  makes  compilation  and  interpretation  of test
  239.      results painless.
  240.  
  241.      Process Control
  242.      With TPHRT, process control applications that require  precise timings
  243.      or  precision  delays  are  easy  to  implement.    No longer will the
  244.      application developer have to make an educated guess as to how  long a
  245.      critical interrupt is taking to service an I/O port as TPHRT  can time
  246.      virtually any hardware or software interrupt and provide the developer
  247.      with  precise  accurate  timings  of  the  critical  procedure.    The
  248.      precision delay  functions  allow  the  programmer  to  implement data
  249.      acquisition loops with microsecond resolution.
  250.  
  251.      Timing and Scoring
  252.      TPHRT  is the perfect "timer engine" to build  a  timing  and  scoring
  253.      system for use in nearly any competitive event.  With  its microsecond
  254.      resolution and self calibration features, TPHRT surpasses conventional
  255.      sports   timing  equipment  resolution  and  allows  the   application
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.      developer to  package  high  resolution  timing  and  complete scoring
  268.      functionality in a single package.
  269.  
  270.      Library Source Code Included
  271.      Since the source code  to  the  TPHRT  linkable libraries is included,
  272.      users needing  a particular timing function not implemented can modify
  273.      the TPHRT functions to suit their particular requirements.
  274.  
  275.  
  276.      Functional Overview
  277.  
  278.  
  279.      The  functionality  of  TPHRT  can  be divided into  several  distinct
  280.      categories of timer services:
  281.  
  282.      TPHRT Timer Logic
  283.      These functions initialize  the  TPHRT  timing  system,  calibrate the
  284.      timing logic, provide a low level interface to the PC timing hardware,
  285.      and perform miscellaneous timing functions that  are  generally hidden
  286.      from  the  user.  Some of these functions will be of interest to users
  287.      who  need to design their own timer functions and want to build on the
  288.      TPHRT low level timer logic.
  289.  
  290.      Generic Timer Functions
  291.      These  functions allow the user to  control  arbitrary  event  timers.
  292.      Functions exist to start, stop,  suspend,  resume,  name,  get elapsed
  293.      time  and activation counts, and to  generate  detailed  reports  that
  294.      summarize  all  timer  activity.  Timer  reports may be output to  the
  295.      display, a disk  file,  or  to  the printer. A setmode function allows
  296.      users to run timers  with  interrupts enabled or disabled.  The number
  297.      of timers active concurrently is restricted  only by available memory.
  298.  
  299.      BIOS Interrupt Timer Functions
  300.      These  functions  are  similar  to  the Generic Timer  Functions,  but
  301.      operate only on BIOS  interrupts.   Using these functions the user may
  302.      install  timer   logic  in  any  PC  interrupt  vector,  and  complete
  303.      information on  that interrupt's activity can be generated.  Interrupt
  304.      timer  reports  list  interrupt  activity  broken  down  by  interrupt
  305.      function (contents of the AH register when the  interrupt  is invoked)
  306.      and text  files  containing  interrupt  function  descriptions  may be
  307.      loaded to describe each  interrupt  function  timer  in the BIOS timer
  308.      report.    Interrupt  description  files  are  provided  for important
  309.      software interrupts in the PC/MSDOS environment.   Multiple interrupts
  310.      may be timed concurrently.
  311.  
  312.      Precision Delay Functions
  313.      These functions allow the user  to  generate  delays  with microsecond
  314.      accuracy. Functions exist to  generate  delays,  query the delay logic
  315.      for available  delay resolution and minimum delay time possible (these
  316.      are hardware dependent), and to  "fine tune" the delay calibration for
  317.      one or more specific delay lengths.
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.                                     TPHRT  2
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.      Theory
  334.  
  335.  
  336.      TPHRT works by directly  interfacing  with channel 0 of the 8253 timer
  337.      chip found in all compatible PCs.  Channel 0 counts  from  65535 to 0,
  338.      when  it  triggers  BIOS  interrupt  8 and begins counting from  65535
  339.      again.  Interrupt 8 is the hardware timer interrupt, and it increments
  340.      the DOS time  of  day  data  word  in  the  BIOS data area, checks for
  341.      diskette motor activity  and  shuts  down  the  motor  if  needed, and
  342.      finally calls BIOS interrupt 1C (hex), which is known as  the software
  343.      timer tick.  At boot time, 1C contains an  IRET  instruction,  meaning
  344.      there is no routine installed in  that  vector.   Since the 8253 has a
  345.      period of 838 nanoseconds, the hardware timer tick occurs every 54.925
  346.      milliseconds, or 18.2 times a second, which is  the  standard software
  347.      time resolution of the PC.   The  8253  count can be read by accessing
  348.      the appropriate IO port, and by reading the 8253 count along  with the
  349.      low word DOS time of day count, we  can  construct  a  high resolution
  350.      time stamp, which  is  the  base  unit  of  time  for TPHRT.  The only
  351.      modifications we make to the PC  environment  is to change the mode of
  352.      channel 0 to give the output count a 50 percent duty cycle, which does
  353.      not  impact  any  other  PC  operations.    Thus  we  have  a  simple,
  354.      unobtrusive,  highly  accurate  time  reference  with  838  nanosecond
  355.      resolution.    Once  a highly accurate time reference is available, we
  356.      can use it to calibrate a  simple  function that contains an inner and
  357.      outer loop to generate precision delays.
  358.  
  359.      The accuracy of TPHRT is as  accurate  as  the 8253 timer chip and the
  360.      ability of the software to measure the overhead in retrieving the 8253
  361.      and DOS time of day data.  With the advent of  advanced  chips  in the
  362.      80286 and 80386 class, the  effects  of  instruction  prefetch queues,
  363.      pipelining, and  cache memory become significant and the same sequence
  364.      of  instructions  may  take  different  amounts  of  time  to  execute
  365.      depending   on   the   interaction   of  the  processor's  performance
  366.      optimization  mechanisms.    The  end  result  is  twofold:    TPHRT's
  367.      calibration  routines may experience inaccuracies, and software  under
  368.      test  may  give  different timing results on different runs.  Normally
  369.      the "jitter" introduced by these conditions  is  on the order of a few
  370.      microseconds.
  371.  
  372.      A  major  source  of  apparent  erratic timer behavior comes from  the
  373.      interaction of asynchronous software and hardware interrupts  that may
  374.      occur  during a timed interval.  While  the  PC/MSDOS  environment  is
  375.      essentially single-threaded,  there  is  enough  "background" activity
  376.      occurring  in the form of timer and  keyboard  interrupts  that  these
  377.      interrupts  may occur during an timed interval,  and  the  time  these
  378.      interrupts  take  to  complete  are  naturally  counted  in the  timed
  379.      interval.   For very short duration timing a  TPHRT  timer  mode  with
  380.      interrupts disabled is available,  but  that  may  not be suitable for
  381.      longer  duration  timings,  or  when  concurrent  timer   activity  is
  382.      required.  Be aware that few results in  the  PC  environment  will be
  383.      exactly  repeatable,  and  that some variance in the timing results is
  384.      unavoidable.
  385.  
  386.      The high resolution  delay  function of TPHRT is particularly affected
  387.      by  background  interrupts  and  processor   performance  optimization
  388.      mechanisms.    The  initial delay calibration will yield delays with a
  389.      variance of from one to three percent of the requested delay interval.
  390.  
  391.  
  392.  
  393.                                     TPHRT  3
  394.  
  395.  
  396.  
  397.  
  398.  
  399.      Additional functions are available to optimize  the  delay calibration
  400.      to a specific delay interval, and using these functions can reduce the
  401.      delay  error  to  between  zero  and  one  percent,  and thus they are
  402.      recommended for critical applications.
  403.  
  404.  
  405.      TPHRT Function Descriptions
  406.  
  407.  
  408.      The following is  a  brief  synopsis  of the functions found in TPHRT.
  409.      This chapter is meant to give  the  user  a brief overview, and is not
  410.      meant to be a definitive reference.  It  is  essential  that  the user
  411.      review the  complete  function  reference  in  the  Function Reference
  412.      chapter before using any TPHRT function.  Some functions may  not work
  413.      as they would appear at first inspection, and in order to achieve high
  414.      performance, TPHRT has a minimum of internal error checking to prevent
  415.      such catastrophes as NULL pointer references.
  416.  
  417.      TPHRT Timer Logic
  418.  
  419.      Initialization functions
  420.  
  421.      t_request           Requests the number of timers needed.
  422.      t_start             Initializes the TPHRT timer logic.
  423.      t_stop              Shuts down TPHRT and frees allocated memory.
  424.  
  425.      Internal functions
  426.  
  427.      t_get               Gets TPHRT time stamp with interrupts
  428.                          enabled.
  429.      t_hires_entry       Gets TPHRT time stamp with interrupts
  430.                          disabled.  8253 count is reset.
  431.      t_hires_exit        Gets TPHRT time stamp and restores interrupts
  432.      t_diff              Calculates elapsed time difference between
  433.                          two TPHRT time stamps.
  434.      t_calib             Calibrates TPHRT timer logic, resets all
  435.                          timers, and calls the delay calibration
  436.                          function.
  437.      t_bios_entry        Receives timer start request from interrupt
  438.                          service routine.
  439.      t_bios_exit         Receives timer stop request from interrupt
  440.                          service routine.
  441.      t_bios_load_desc    Loads interrupt function description file
  442.      t_hook_int          Installs timer calls in specified interrupt
  443.                          vector.
  444.      t_unhook_int        Removes timer calls from specified interrupt
  445.                          vector.
  446.      t_delay_calib       Calibrates delay logic.
  447.  
  448.      t_request is called by the user to specify the number of timers needed
  449.      for generic timer  operations  if  the  user  wishes  to  override the
  450.      default  number  of  timers provided (10).    Since  each  timer  data
  451.      structure is  allocated dynamically, the number of timers available is
  452.      restricted by the amount of heap available and the constraints  of the
  453.      memory model you are using. If  t_request  is used in your program, it
  454.      must be called before t_start.
  455.  
  456.  
  457.  
  458.  
  459.                                     TPHRT  4
  460.  
  461.  
  462.  
  463.  
  464.  
  465.      t_start allocates the appropriate  amount  of  heap  for the number of
  466.      timers requested, initializes those  timers,  and  calibrates  the low
  467.      level timer routines.   t_start  must always be invoked prior to using
  468.      any other timer functions with the exception of t_request.
  469.  
  470.      t_stop deallocates all allocated heap  associated  with  generic timer
  471.      activity and shuts down the timer logic.  t_stop must be  called prior
  472.      to program termination, and  no  further calls to TPHRT should be made
  473.      unless t_start is invoked first.
  474.  
  475.      The TPHRT internal functions of primary interest to the programmer are
  476.      t_get, which is the interface to  the  8253 timer chip;  t_diff, which
  477.      calculates  the  elapsed  time  between  two  TPHRT  time stamps;  and
  478.      t_calib, which calibrates the  timer  and delay logic to the host run-
  479.      time environment.
  480.  
  481.      Generic TPHRT Timer Functions
  482.  
  483.      This class of functions implement general purpose timer functionality.
  484.  
  485.      t_entry             Starts the specified timer.
  486.      t_exit              Stops the specified timer.
  487.      t_suspend           Suspends the specified timer.
  488.      t_resume            Resumes the specified suspended timer.
  489.      t_setmode           Specifies timer mode - interrupts on or off.
  490.      t_ask_timer         Gets accumulated activations and elapsed time
  491.                          for the specified timer
  492.      t_cvt_time          Converts microseconds to MM:SS.xxxxxx string.
  493.      t_reset             Resets one or all timers.
  494.      t_report            Generates timer report
  495.      t_name              Associates string with specified timer for
  496.                          display in timer report.
  497.      t_rname             Specifies title of timer report.
  498.      t_fname             Specifies destination file for timer report.
  499.      t_set_report        Specifies type of timer report generated.
  500.  
  501.      t_entry  and  t_exit  provide  the  mechanism  to  start  and  stop  a
  502.      microsecond timer.  Timers are specified by number from 0 to n-1 in C,
  503.      and  1  to  n in Pascal.  The number of  timers  available  is  10  by
  504.      default, but the user can use  t_request  to request as many timers as
  505.      available heap allows.  Multiple timers may be active at the same time
  506.      if interrupts are enabled.
  507.  
  508.      t_suspend and t_resume suspend and resume a timer previously activated
  509.      by t_entry.  Timer activation count is not  incremented  when t_resume
  510.      is called, which is useful if you are using timer activation counts to
  511.      track subroutine  activations in a profiling application, and for some
  512.      reason you wish to pause  the timer during the subroutine's activation
  513.      (perhaps before a call to another routine) and then restart it.
  514.  
  515.      t_setmode  allows  the  user to specify whether  timers  operate  with
  516.      interrupts enabled or disabled.   With  interrupts  enabled, intervals
  517.      greater than 54925 microseconds may  be timed, and multiple timers may
  518.      be active concurrently.  With  interrupts  disabled,  the  timer logic
  519.      will "roll over" after 54925 usecs,  and  only one timer may be active
  520.      at any time.  Timing short duration events with interrupts disabled is
  521.  
  522.  
  523.  
  524.  
  525.                                     TPHRT  5
  526.  
  527.  
  528.  
  529.  
  530.  
  531.      useful  if  background   system  interrupts  are  causing  significant
  532.      variations in timer results.
  533.  
  534.      t_ask_timer will return to  the  user  the  activation count and total
  535.      elapsed time in microseconds for the specified timer.  t_cvt_time will
  536.      convert  a microsecond time count into a  printable  string  with  the
  537.      format MM:SS.xxxxxx.  Timer activation counts and  accumulated elapsed
  538.      time can be reset to zero by using t_reset.
  539.  
  540.      t_report generates a complete  listing  of  all  timer activity.  This
  541.      listing can be directed to the display, a  disk  file,  or  a printer.
  542.      t_rname allows the user to give the timer report a  descriptive title.
  543.      t_fname overrides the default disk file name for  timer  reports going
  544.      to disk.  t_name allows the  user  to assign a descriptive text string
  545.      to  a  timer number - this string will be printed next  to  the  timer
  546.      number in the timer report.    Finally,  t_set_report  determines what
  547.      timers are listed on  the  timer report: either only those timers that
  548.      had  been activated, or all timers,  regardless  of  their  activation
  549.      count, up to the highest timer number activated.
  550.  
  551.      BIOS Interrupt Timer Functions
  552.  
  553.      This  class  of  functions   implement   the   BIOS   interrupt  timer
  554.      functionality.
  555.  
  556.      t_bios_start        Installs timers in specified interrupt
  557.                          vectors.
  558.      t_bios_stop         Removes all timers from interrupt vectors.
  559.      t_bios_suspend      Suspends specified interrupt timing.
  560.      t_bios_resume       Resumes interrupt timing in the specified
  561.                          vectors.
  562.      t_bios_set_user     Assigns timer to user specified interrupt.
  563.      t_bios_set_file     Assigns interrupt function description file
  564.                          name to the user specified interrupt timer.
  565.      t_bios_ask          Returns activations and elapsed for the
  566.                          specified interrupt function
  567.      t_bios_reset        Resets one or all function timers of the
  568.                          specified interrupt vector.
  569.      t_bios_report       Generates BIOS interrupt timer report.
  570.      t_bios_rname        Specifies title of BIOS timer report.
  571.      t_bios_fname        Specifies destination file for BIOS timer
  572.                          report.
  573.  
  574.      t_bios_start  initializes  BIOS interrupt timing  for  the  interrupts
  575.      specified.    Heap  is  allocated  for the required  data  structures,
  576.      interrupt function description files  are  loaded  if available, and a
  577.      new interrupt service  routine  for  each  interrupt  to  be  timed is
  578.      inserted in  the  interrupt  vector  table.    t_bios_stop essentially
  579.      reverses  this  process,  freeing  allocated  heap  and  restoring the
  580.      previous interrupt service vectors.    The  BIOS timer data structures
  581.      are separate from the generic timer structures, and thus t_request has
  582.      no effect on BIOS interrupt timer activity.
  583.  
  584.      t_bios_suspend and  t_bios_resume allow the user to suspend and resume
  585.      BIOS interrupt timing  of  the specified interrupt(s).  All interrupts
  586.      to be timed must be installed by t_bios_start, but timing can  then be
  587.      immediately suspended by t_bios_suspend until the point in the program
  588.  
  589.  
  590.  
  591.                                     TPHRT  6
  592.  
  593.  
  594.  
  595.  
  596.  
  597.      that the user actually wants timing  to  begin, when it can be resumed
  598.      with t_bios_resume.
  599.  
  600.      t_bios_set_user enables the user to specify an interrupt  to  be timed
  601.      that has not been provided for by TPHRT.  Each interrupt that is timed
  602.      requires new interrupt  service  routine that when activated, starts a
  603.      timer, calls the old vector, then stops the appropriate timer.   TPHRT
  604.      provides new timer ISRs for the major device, EMS,  Mouse,  and  MSDOS
  605.      interrupts, along with  a  spare  ISR  that  can be used for any other
  606.      interrupt the user might want to time.   t_bios_set_user  assigns this
  607.      spare timer ISR to the specified interrupt, allowing the user  to time
  608.      any interrupt vector in the PC environment.   If  the  interrupt  is a
  609.      software interrupt that has specific functions (as requested by the AH
  610.      register when the  interrupt  is  invoked)  the  user  may  specify an
  611.      interrupt function description  file using t_bios_set_file which loads
  612.      a text file containing interrupt function descriptions if that file is
  613.      in the current directory.    Interrupt  function description files are
  614.      provided for all the software interrupts TPHRT has standard timer ISRs
  615.      for.
  616.  
  617.      t_bios_ask   and  t_bios_reset  function  like  their  generic   timer
  618.      counterparts and allow the user to request specific BIOS timer results
  619.      or to reset  those results to zero.
  620.  
  621.      t_bios_report, t_bios_rname, and  t_bios_fname modify and generate the
  622.      BIOS timer report in the same way as their generic  timer counterparts
  623.      t_report, t_rname, and  t_fname  generate and modify the generic timer
  624.      report.
  625.  
  626.      Be sure and carefully review the documentation for t_bios_start before
  627.      using the BIOS interrupt timing functions.
  628.  
  629.      Delay Functions
  630.  
  631.      This class of functions  implement  the  microsecond  resolution delay
  632.      functionality.
  633.  
  634.      t_ask_delay         Requests parameters for requested delay time.
  635.      t_do_delay          Executes delay with interrupts disabled.
  636.      t_do_delay_wints    Executes delay with interrupts enabled.
  637.      t_calc_delay_ff     Optimizes delay calibration to a specified
  638.                          delay duration.
  639.      t_get_delay_ff      Returns delay calibration optimization.
  640.      t_set_delay_ff      Sets current delay calibration optimization.
  641.      t_min_delay         Returns minimum delay possible with current
  642.                          hardware.
  643.      t_res_delay         Returns delay resolution possible with
  644.                          current hardware
  645.  
  646.      t_ask_delay   requests  delay  parameters  for  the  specified   delay
  647.      interval.    These  parameters  are  stored in a user allocated  TPHRT
  648.      defined  data structure and are passed  to  either  t_do_delay,  which
  649.      generates  the  delay  with  interrupts disabled, or t_do_delay_wints,
  650.      which generates the delay with interrupts enabled.
  651.  
  652.      t_calc_delay_ff,  t_set_delay_ff, and t_get_delay_ff, allows the  user
  653.      to  have  the  TPHRT  delay  logic  "fine  tune"  its calibration to a
  654.  
  655.  
  656.  
  657.                                     TPHRT  7
  658.  
  659.  
  660.  
  661.  
  662.  
  663.      particular delay interval.   t_calc_delay_ff  calculates  and installs
  664.      the  new  delay  calibration  optimization, t_set_delay_ff enables the
  665.      user  to   install   a   previously   calculated   optimization,   and
  666.      t_get_delay_ff retrieves the current delay optimization.
  667.  
  668.      t_min_delay returns the minimum  delay  possible  in the host run-time
  669.      environment.  t_res_delay returns the resolution of the delay function
  670.      in the host run-time environment.
  671.  
  672.  
  673.      Examples
  674.  
  675.  
  676.      While  the  accompanying  pages  spell  out the functions of TPHRT  in
  677.      detail, as the saying goes, "a picture is worth a thousand words".  In
  678.      keeping with that philosophy,  we  have  included several source files
  679.      that demonstrate different  areas  of TPHRT functionality. They are as
  680.      follows:
  681.  
  682.      DEMO             Basic  TPHRT operation.  Shows inline and  subroutine
  683.                       timing, report generation.
  684.  
  685.      TESTBIOS         BIOS interrupt timing.
  686.  
  687.      SEEKTEST         Hard disk seek  test  benchmark.    Uses  both inline
  688.                       timers and BIOS interrupt timing to  fully  test disk
  689.                       seek performance.
  690.  
  691.      DELAY            Demonstration of high resolution delay functionality.
  692.  
  693.      WATCH            Full function Taylor Split stopwatch.   Shows  how to
  694.                       activate timers with a user written interrupt service
  695.                       routine.
  696.  
  697.      These programs are carefully commented and  provide  valuable insights
  698.      into effective TPHRT operation.
  699.  
  700.  
  701.      Technical Support
  702.  
  703.  
  704.      Technical  support for licensed users of TPHRT  is  available  by  the
  705.      following methods:
  706.  
  707.         1.  By US Mail directed to P.O. Box 22, Mt. Pleasant MI 48804.
  708.  
  709.         2.  By   Compuserve  electronic   (Easyplex)   mail   directed   to
  710.             73047,1765.
  711.  
  712.  
  713.      Shareware
  714.  
  715.  
  716.      This software is distributed as "Shareware", which allows  you  to use
  717.      the complete product  on  an  evaluation  basis  to get a feel for its
  718.      quality, functionality, and value  to  you as a developer or end user.
  719.      At the end of your evaluation (14 days is a  widely  accepted time for
  720.  
  721.  
  722.  
  723.                                     TPHRT  8
  724.  
  725.  
  726.  
  727.  
  728.  
  729.      the evaluation period) you may continue to use the software product by
  730.      sending in a registration  fee  to  the  program author/vendor, or you
  731.      must discontinue use of the software and are free to pass your copy on
  732.      to another user for evaluation.   The Shareware concept allows quality
  733.      software  to   be  distributed  at  far  less  cost  than  traditional
  734.      commercial products, and allows the user to "try before you buy".
  735.  
  736.      TPHRT is a single language functional subset of PCHRT,  the  PC  Timer
  737.      Toolbox distributed through traditional  commercial  channels  by Ryle
  738.      Design.    MSCHRT  for  Microsoft  C  and  TCHRT  for Turbo C are also
  739.      available as Shareware, and  provide  the  same  suite of functions as
  740.      TPHRT.
  741.  
  742.      Registration of TPHRT costs $20.00,  and in return users receive units
  743.      for  TP 5 & 5.5 (without the  shareware  messages),  complete  library
  744.      source code, and technical  support  by  US  Mail and Compuserv Email.
  745.      Distribution of TPHRT object  code  in  commercial applications is not
  746.      permitted.
  747.  
  748.      Users  developing commerical applications or needing additional  timer
  749.      functionality should purchase PCHRT, the commerical version  of TPHRT,
  750.      which costs $49.95.  PCHRT includes all the functions of  TPHRT, along
  751.      with three  new timer functions, five new synchronous alarm functions,
  752.      four functions to run the timer tick interrupt at a user defined rate,
  753.      and two utilities to  time  execution  and  profile interrupts of most
  754.      executable programs without recompilation.  PCHRT comes with libraries
  755.      for  Turbo  C  and MSC in small, medium, compact, and large models, as
  756.      well  as units for Turbo Pascal V5 and V5.5.  Full library source code
  757.      for both Pascal and C is provided, along  with  a  printed  manual and
  758.      telephone technical support.  Distribution  of  PCHRT  object  code in
  759.      commercial applications is permitted without royalties.
  760.  
  761.      An order form  for  these  products  appears  as the last page of this
  762.      document.
  763.  
  764.  
  765.  
  766.  
  767.  
  768.  
  769.  
  770.  
  771.  
  772.  
  773.  
  774.  
  775.  
  776.  
  777.  
  778.  
  779.  
  780.  
  781.  
  782.  
  783.  
  784.  
  785.  
  786.  
  787.  
  788.  
  789.                                     TPHRT  9
  790.  
  791.  
  792.  
  793.  
  794.  
  795.  
  796.  
  797.  
  798.  
  799.  
  800.  
  801.  
  802.  
  803.  
  804.  
  805.  
  806.  
  807.  
  808.  
  809.  
  810.  
  811.  
  812.  
  813.  
  814.  
  815.  
  816.  
  817.  
  818.  
  819.  
  820.  
  821.  
  822.  
  823.  
  824.  
  825.  
  826.  
  827.  
  828.  
  829.  
  830.  
  831.  
  832.  
  833.  
  834.  
  835.  
  836.  
  837.  
  838.  
  839.  
  840.  
  841.  
  842.  
  843.  
  844.  
  845.  
  846.  
  847.  
  848.  
  849.  
  850.  
  851.  
  852.  
  853.  
  854.  
  855.                                     TPHRT  10
  856.  
  857.  
  858.  
  859.  
  860.  
  861.  
  862.  
  863.  
  864.  
  865.  
  866.  
  867.                             TPHRT Function Reference
  868.  
  869.  
  870.      t_ask_delay
  871.  
  872.  
  873.      Purpose          Fills delay parameter structure with  required values
  874.                       for requested delay interval
  875.  
  876.      Pascal           procedure  t_ask_delay(usec  :  longint;  var   dp  :
  877.                       tdelay_type)
  878.  
  879.      Synopsis         Parameters accepted by the delay functions are stored
  880.                       in  a  TPHRT  defined,  user allocated data structure
  881.                       tdelay_type.   t_ask_delay accepts the desired  delay
  882.                       interval  in  microseconds,  and  fills   the  passed
  883.                       tdelay_type structure with the appropriate parameters
  884.                       to generate the requested delay.  This data structure
  885.                       is    then    passed    to   either   t_do_delay   or
  886.                       t_do_delay_wints,   where   the   actual   delay   is
  887.                       generated.
  888.  
  889.      Caveat           None
  890.  
  891.      See Also         t_do_delay, t_do_delay_wints
  892.  
  893.  
  894.      t_ask_timer
  895.  
  896.  
  897.      Purpose          Returns activation  and  elapsed  time  count  for  a
  898.                       specified timer
  899.  
  900.      Pascal           procedure  t_ask_timer(tnum  :   integer;   var  hits
  901.                       :longint; var elapsed : longint)
  902.  
  903.      Synopsis         The  user may retrieve activation counts and  elapsed
  904.                       time  (in 2microseconds)  for  the  specified  timer.
  905.                       Timers are specified from 0 to n-1 in C and from 1 to
  906.                       n in Pascal.  The number of timers n defaults  to 10,
  907.                       but t_request  may  be  called  prior  to  t_start to
  908.                       increase that number.
  909.  
  910.      Caveat           No range  checking is done.  A NULL pointer reference
  911.                       is possible if information on a non-existant timer is
  912.                       requested.
  913.  
  914.      See Also         t_request, t_reset
  915.  
  916.  
  917.  
  918.  
  919.  
  920.  
  921.                                     TPHRT  11
  922.  
  923.  
  924.  
  925.  
  926.  
  927.      t_bios_ask
  928.  
  929.  
  930.      Purpose          Returns activation count and elapsed time for  one or
  931.                       all functions associated with a BIOS interrupt timer
  932.  
  933.      Pascal           procedure t_bios_ask(whichint : integer; whichfunc  :
  934.                       integer; var hits : longint; var elapsed : longint)
  935.  
  936.      Synopsis         The users passes a single BIOS  timer  interrupt mask
  937.                       (see  t_bios_start) and either an interrupt  function
  938.                       in the range of 0 to 255 or -1, which causes  all the
  939.                       interrupt   function  timers  to  be  summed.     The
  940.                       accumulated number of activations and elapsed time in
  941.                       microseconds is returned.
  942.  
  943.                       The summation of all function  timers  by  passing -1
  944.                       feature is useful if a hardware  interrupt  that does
  945.                       not have specific function  classes  is  being timed.
  946.                       Interrupt functions are  specified by the contents of
  947.                       the  AH  register,  and  since  the  AH  register may
  948.                       contain  random, non-specific values when a  hardware
  949.                       interrupt  is invoked, many timers for the  interrupt
  950.                       will show some activity.   These  must  be  summed in
  951.                       order to  determine  the  activity  of  the  hardware
  952.                       interrupt.
  953.  
  954.      Caveat           No range  checking is done.  A NULL pointer reference
  955.                       is possible if information is  requested  on  an non-
  956.                       existant interrupt timer.
  957.  
  958.      See Also         t_bios_start, t_bios_reset
  959.  
  960.  
  961.      t_bios_entry
  962.  
  963.  
  964.      Purpose          Receives  timer  start  requests  from  an  interrupt
  965.                       service routine
  966.  
  967.      Pascal           procedure t_bios_entry(whichint :  integer; whichfunc
  968.                       : integer)
  969.  
  970.      Synopsis         BIOS interrupt vectors  being timed call this routine
  971.                       to start the appropriate  timer  for  this interrupt.
  972.                       Parameter whichfunc is the value in  the  AH register
  973.                       when   the  interrupt  was  invoked,  which  is   the
  974.                       interrupt function requested in a software interrupt.
  975.  
  976.      Caveat           This is  an internal TPHRT procedure and is not meant
  977.                       to be called by the user.
  978.  
  979.      See Also         t_bios_exit
  980.  
  981.  
  982.  
  983.  
  984.  
  985.  
  986.  
  987.                                     TPHRT  12
  988.  
  989.  
  990.  
  991.  
  992.  
  993.      t_bios_exit
  994.  
  995.  
  996.      Purpose          Receives  interrupt  timer  stop  requests   from  an
  997.                       interrupt service routine
  998.  
  999.      Pascal           procedure t_bios_exit(whichint : integer)
  1000.  
  1001.      Synopsis         BIOS interrupt vectors call this routine to  stop the
  1002.                       appropriate timer for this  interrupt.    The current
  1003.                       active function timer  for this interrupt is stopped,
  1004.                       and  if  the  interrupt  was entered recursively, the
  1005.                       previous function timer is restarted.
  1006.  
  1007.      Caveat           This is  an internal TPHRT procedure and is not meant
  1008.                       to be called by the user.
  1009.  
  1010.      See Also         t_bios_entry
  1011.  
  1012.  
  1013.      t_bios_fname
  1014.  
  1015.  
  1016.      Purpose          Specifies a name for the  disk  file  created  by the
  1017.                       BIOS timer report if the disk  destination  option is
  1018.                       selected
  1019.  
  1020.      Pascal           procedure t_bios_fname(fname : string)
  1021.  
  1022.      Synopsis         By calling t_bios_report(1)  the BIOS timer report is
  1023.                       generated  and  sent  to  an  ASCII disk file.    The
  1024.                       default  name   for   this   file   is  BIOSTIME.TXT.
  1025.                       t_bios_fname  allows the user to specify a  different
  1026.                       filename,   with   complete   disk,  path,  and  file
  1027.                       specification.
  1028.  
  1029.      Caveat           Maximum  disk/path/filename  string   length   is  67
  1030.                       characters
  1031.  
  1032.      See Also         t_bios_report
  1033.  
  1034.  
  1035.      t_bios_load_desc
  1036.  
  1037.  
  1038.      Purpose          Loads   an   interrupt   description  file  into  the
  1039.                       appropriate interrupt timer data structure
  1040.  
  1041.      Pascal           procedure t_bios_load_desc(whichint :  integer; fname
  1042.                       : string)
  1043.  
  1044.      Synopsis         Each  interrupt  vector  being  timed   contains  256
  1045.                       timers,  one for each possible interrupt function  as
  1046.                       indicated  by  the  AH   register.      An  interrupt
  1047.                       description  file  contains  brief  twenty  character
  1048.                       descriptions  of  each  interrupt  function,  and  if
  1049.                       loaded, these will appear  along  with  the interrupt
  1050.  
  1051.  
  1052.  
  1053.                                     TPHRT  13
  1054.  
  1055.  
  1056.  
  1057.  
  1058.  
  1059.                       function  number in the BIOS interrupt timer  report.
  1060.                       whichint   is  a  BIOS  timer  interrupt  mask   (see
  1061.                       t_bios_start),  and  data_file  is the disk/path/file
  1062.                       descriptor.  No error is generated  if  the specified
  1063.                       file is not found.
  1064.  
  1065.                       See  one of the supplied interrupt description  files
  1066.                       (such as 10.INT) for the layout of these files.
  1067.  
  1068.                       This routine is called automatically by t_bios_start.
  1069.  
  1070.      Caveat           No range checking is done.  NULL pointer reference is
  1071.                       possible.
  1072.  
  1073.      See Also         t_bios_start, t_bios_set_file
  1074.  
  1075.  
  1076.      t_bios_report
  1077.  
  1078.  
  1079.      Purpose          Generates BIOS interrupt timer report
  1080.  
  1081.      Pascal           procedure t_bios_report(integer : whereto)
  1082.  
  1083.      Synopsis         This routine generates a  complete  timer  report for
  1084.                       all active BIOS  interrupt timers.  whereto specifies
  1085.                       the report's  destination - 0 sends the report to the
  1086.                       display, 1 to a disk file, and 2 to a printer.
  1087.  
  1088.      Caveat           None.
  1089.  
  1090.      See Also         t_bios_rname, t_bios_fname
  1091.  
  1092.  
  1093.      t_bios_resume
  1094.  
  1095.  
  1096.      Purpose          Resumes suspended BIOS interrupt timing
  1097.  
  1098.      Pascal           procedure t_bios_resume(biosmask : integer)
  1099.  
  1100.      Synopsis         This  routine  enables   previously   suspended  BIOS
  1101.                       interrupt  timing.  biosmask contains the BIOS  timer
  1102.                       bitmask (see t_bios_start)  of the interrupts to have
  1103.                       timing re-enabled.
  1104.  
  1105.      Caveat           No range checking is done.  NULL pointer reference is
  1106.                       possible if a interrupt is  referenced  that  was not
  1107.                       setup by t_bios_start.
  1108.  
  1109.      See Also         t_bios_suspend, t_bios_start
  1110.  
  1111.  
  1112.  
  1113.  
  1114.  
  1115.  
  1116.  
  1117.  
  1118.  
  1119.                                     TPHRT  14
  1120.  
  1121.  
  1122.  
  1123.  
  1124.  
  1125.      t_bios_reset
  1126.  
  1127.  
  1128.      Purpose          Resets one or  all  timers  associated  with  a timed
  1129.                       interrupt
  1130.  
  1131.      Pascal           procedure t_bios_reset(whichint :  integer; whichfunc
  1132.                       : integer)
  1133.  
  1134.      Synopsis         This function allows the  user  to  reset  either one
  1135.                       specific  or  all  function  timers associated with a
  1136.                       timed interrupt.  Specific function timers are in the
  1137.                       range of 0 to 255.  Passing -1  for  whichfunc resets
  1138.                       all  256  timers  associated  with a timed interrupt.
  1139.                       The interrupt is specified  by  whichint  which  is a
  1140.                       single BIOS interrupt timer mask (see t_bios_start).
  1141.  
  1142.      Caveat           No range checking is done.  NULL pointer reference is
  1143.                       possible   if  a  non-existant  interrupt  timer   is
  1144.                       specified.
  1145.  
  1146.      See Also         t_bios_start, t_bios_ask
  1147.  
  1148.  
  1149.      t_bios_rname
  1150.  
  1151.  
  1152.      Purpose          Specifies title for BIOS timer report
  1153.  
  1154.      Pascal           procedure t_bios_rname(rname : string)
  1155.  
  1156.      Synopsis         This function  allows the user to specify a title for
  1157.                       the  BIOS  interrupt  timer  report.    If   none  is
  1158.                       specified,  the  title  used  is Bios Interrupt Timer
  1159.                       Summary.  The title is horizontally centered.
  1160.  
  1161.      Caveat           Max string length is 80 characters.
  1162.  
  1163.      See Also         t_bios_report, t_bios_fname
  1164.  
  1165.  
  1166.      t_bios_set_file
  1167.  
  1168.  
  1169.      Purpose          Sets the interrupt  function description file for the
  1170.                       user specified interrupt timer
  1171.  
  1172.      Pascal           procedure t_bios_set_file(ufile : string)
  1173.  
  1174.      Synopsis         When a user specifies the optional interrupt  to time
  1175.                       using  t_bios_set_user, a file of interrupt  function
  1176.                       descriptions   may  also  be  specified  using   this
  1177.                       function.
  1178.  
  1179.      Caveat           Max file description length is 67 characters.
  1180.  
  1181.      See Also         t_bios_load_desc, t_bios_set_file
  1182.  
  1183.  
  1184.  
  1185.                                     TPHRT  15
  1186.  
  1187.  
  1188.  
  1189.  
  1190.  
  1191.      t_bios_set_user
  1192.  
  1193.  
  1194.      Purpose          Specifies the optional interrupt to time
  1195.  
  1196.      Pascal           procedure t_bios_set_user(user_int : integer)
  1197.  
  1198.      Synopsis         The  TPHRT  BIOS timing functionality  has  built  in
  1199.                       support for the various BIOS interrupts of interest -
  1200.                       disk, CRT, serial,  parallel, DOS, EMS, keyboard, and
  1201.                       mouse.   This function allows the user to specify any
  1202.                       other interrupt to be timed, and when t_bios_start is
  1203.                       invoked with the  USER  bit set in the timer bitmask,
  1204.                       the interrupt specified by t_bios_set_user  will have
  1205.                       timers inserted in its vector.
  1206.  
  1207.      Caveat           The  ISR  supplied  that  is  hooked  into  the  user
  1208.                       specified interrupt (t_new_user in the  .ASM modules)
  1209.                       does not propagate the  FLAGS  register.   If you are
  1210.                       attempting to time  a software interrupt that returns
  1211.                       meaningful information  in  the  FLAGS  register, you
  1212.                       should  modify  the  t_new_user  routine so that it's
  1213.                       last instruction is a RETF 2 instead of  IRET.   This
  1214.                       is documented in the t_new_user code.
  1215.  
  1216.      See Also         t_bios_start, t_bios_set_file
  1217.  
  1218.  
  1219.      t_bios_start
  1220.  
  1221.  
  1222.      Purpose          Initializes BIOS interrupt timing
  1223.  
  1224.      Pascal           procedure t_bios_start(biosmask : integer)
  1225.  
  1226.      Synopsis         This function initializes BIOS interrupt timing.  The
  1227.                       interrupts to be timed are  selected  by  passing the
  1228.                       appropriate bitmask:
  1229.  
  1230.                       CRT10       INT 10h Video Services
  1231.  
  1232.                       DISK        INT 13h Disk Services
  1233.  
  1234.                       COM         INT 14h Serial Port Services
  1235.  
  1236.                       KEYBD       INT 16h Keyboard Services
  1237.  
  1238.                       PRT         INT 17h Printer Services
  1239.  
  1240.                       DOS21       INT 21h MSDOS System Services
  1241.  
  1242.                       MOUSE       INT 33h Mouse Services
  1243.  
  1244.                       EMS         INT 67h EMS Services
  1245.  
  1246.                       USER        User Specified Interrupt
  1247.  
  1248.  
  1249.  
  1250.  
  1251.                                     TPHRT  16
  1252.  
  1253.  
  1254.  
  1255.  
  1256.  
  1257.                       As an  example, to insert timers in the DOS interrupt
  1258.                       and   the   disk   interrupt,   one    would   invoke
  1259.                       t_bios_start(DISK+DOS21).
  1260.  
  1261.                       Each  interrupt timed  actually  has  256  individual
  1262.                       timers,  one  for  each  possible  value  in  the  AH
  1263.                       register,  which indicates what specific function  of
  1264.                       that interrupt has been requested.    The  timer data
  1265.                       structure   is   allocated  dynamically,   and   each
  1266.                       structure requires approximately 9200 bytes, so there
  1267.                       is a limit imposed by  the memory model being used as
  1268.                       to  how  many  interrupt  timers  may  be  requested.
  1269.                       t_bios_start returns FALSE  in  C  if  the  amount of
  1270.                       memory  needed  is not available,  while  a  run-time
  1271.                       error occurs in Turbo Pascal.
  1272.  
  1273.                       If the USER bitmask is  to  be  used, t_bios_set_user
  1274.                       must  be  invoked  prior  to t_bios_start to indicate
  1275.                       what interrupt the USER bitmask will time.
  1276.  
  1277.                       Interrupt   function   description  files   for   the
  1278.                       supported interrupts are supplied, and will be loaded
  1279.                       if they are present  in  the  run-time directory.  As
  1280.                       these  will  dramatically  improve  the   information
  1281.                       presented in the BIOS  interrupt  timer  report, they
  1282.                       are  recommended.  t_bios_set_file associates a  file
  1283.                       with the USER selected interrupt.
  1284.  
  1285.                       If testing code with  BIOS  interrupt  timing active,
  1286.                       and the code fails prior to calling t_bios_stop, then
  1287.                       you  should immediately reboot your computer, as  the
  1288.                       interrupt vectors being timed  are  pointing  to non-
  1289.                       existant code.
  1290.  
  1291.      Caveat           Approximately  9200  bytes  are  required   for  each
  1292.                       interrupt to be timed.  Memory constraints can affect
  1293.                       this function.
  1294.  
  1295.      See Also         t_bios_stop,     t_bios_set_user,    t_bios_set_file,
  1296.                       t_bios_suspend, t_bios_resume
  1297.  
  1298.  
  1299.      t_bios_stop
  1300.  
  1301.  
  1302.      Purpose          Stops all BIOS interrupt timing
  1303.  
  1304.      Pascal           procedure t_bios_stop;
  1305.  
  1306.      Synopsis         This  function removes all timers from all  interrupt
  1307.                       vectors selected by t_bios_start and  deallocates all
  1308.                       memory associated with those timers.
  1309.  
  1310.      Caveat           This function must be called prior to program exit in
  1311.                       order to restore the interrupt environment.    If the
  1312.                       code under  test  fails  prior  to  t_bios_start  the
  1313.  
  1314.  
  1315.  
  1316.  
  1317.                                     TPHRT  17
  1318.  
  1319.  
  1320.  
  1321.  
  1322.  
  1323.                       interrupt  vectors  being  timed  will be pointing to
  1324.                       non-existant code, and a system hang is likely.
  1325.  
  1326.      See Also         t_bios_start, t_bios_suspend, t_bios_resume
  1327.  
  1328.  
  1329.      t_bios_suspend
  1330.  
  1331.  
  1332.      Purpose          Suspends interrupt timing selected by t_bios_start
  1333.  
  1334.      Pascal           procedure t_bios_suspend(biosmask : integer)
  1335.  
  1336.      Synopsis         BIOS  interrupt timing is initiated by  t_bios_start,
  1337.                       and terminated by t_bios_stop.   t_bios_suspend gives
  1338.                       the user the ability to selectively disable timing on
  1339.                       a particular interrupt or  interrupts  by  passing an
  1340.                       appropriate  biosmask  (see   t_bios_start).     This
  1341.                       suspended interrupt timing may  be  later  resumed by
  1342.                       invoking t_bios_resume.
  1343.  
  1344.      Caveat           No range checking is done.  NULL pointer reference is
  1345.                       possible   if  a  non-existant  interrupt  timer   is
  1346.                       referenced.
  1347.  
  1348.      See Also         t_bios_resume, t_bios_start, t_bios_stop
  1349.  
  1350.  
  1351.      t_calc_delay_ff
  1352.  
  1353.  
  1354.      Purpose          Optimizes  delay calibration  for  a  specific  delay
  1355.                       interval
  1356.  
  1357.      Pascal           function   t_calc_delay_ff(delay_time    :   longint;
  1358.                       ints_or_not : integer)
  1359.  
  1360.      Synopsis         This  function  optimizes  delay  calibration   to  a
  1361.                       specific  delay interval.  ints_or_not can be  either
  1362.                       INTS_ON,  indicating a delay with interrupts  enabled
  1363.                       should  be used for the optimization calculation,  or
  1364.                       NO_INTS_ON,   which  indicates  that  a  delay   with
  1365.                       interrupts disabled should be  used.    This function
  1366.                       sets a  global value that is used by t_ask_delay, and
  1367.                       the value is also returned,  so that it may be stored
  1368.                       for later use with the delay interval optimized.
  1369.  
  1370.      Caveat           None
  1371.  
  1372.      See Also         t_set_delay_ff, t_get_delay_ff, t_ask_delay
  1373.  
  1374.  
  1375.      t_calib
  1376.  
  1377.  
  1378.      Purpose          Calibrates the TPHRT timer and delay logic
  1379.  
  1380.  
  1381.  
  1382.  
  1383.                                     TPHRT  18
  1384.  
  1385.  
  1386.  
  1387.  
  1388.  
  1389.      Pascal           procedure t_calib
  1390.  
  1391.      Synopsis         This function calibrates the  low  level  TPHRT timer
  1392.                       and delay logic.   It  is  called  by t_start, so the
  1393.                       user  need  not  explicitly  call this routine unless
  1394.                       additional delay calibration is needed after a system
  1395.                       parameter has been  modified  during a timing run - a
  1396.                       keyboard initiated system clock  speed  change  is an
  1397.                       example.    t_calib  calls t_delay_calib to calibrate
  1398.                       the TPHRT delay logic.
  1399.  
  1400.      Caveat           None
  1401.  
  1402.      See Also         t_delay_calib
  1403.  
  1404.  
  1405.      t_cvt_time
  1406.  
  1407.  
  1408.      Purpose          Converts a microsecond count to a MM:SS.xxxxxx format
  1409.                       string
  1410.  
  1411.      Pascal           function t_cvt_time(usec : longint; tstring : string)
  1412.                       : string
  1413.  
  1414.      Synopsis         This function accepts a microsecond count and returns
  1415.                       a printable character string in a simple time format.
  1416.                       This function is useful to  the  user  who  wishes to
  1417.                       build custom timer reports.
  1418.  
  1419.      Caveat           Destination string length should be 13 characters.
  1420.  
  1421.      See Also         t_ask_timer, t_bios_ask
  1422.  
  1423.  
  1424.      t_delay_calib
  1425.  
  1426.  
  1427.      Purpose          Calibrates the TPHRT delay logic
  1428.  
  1429.      Pascal           procedure t_delay_calib
  1430.  
  1431.      Synopsis         This  function  calibrates the delay  loops  used  to
  1432.                       generate  precision  microsecond  delays.  Additional
  1433.                       calibration   is   available   from  t_calc_delay_ff.
  1434.                       t_delay_calib is called by t_calib, so the  user need
  1435.                       not call it explicitly.
  1436.  
  1437.      Caveat           None
  1438.  
  1439.      See Also         t_calib, t_calc_delay_ff
  1440.  
  1441.  
  1442.  
  1443.  
  1444.  
  1445.  
  1446.  
  1447.  
  1448.  
  1449.                                     TPHRT  19
  1450.  
  1451.  
  1452.  
  1453.  
  1454.  
  1455.      t_diff
  1456.  
  1457.  
  1458.      Purpose          Calculates  the difference  between  two  TPHRT  time
  1459.                       stamps
  1460.  
  1461.      Pascal           function t_diff(start, stop : TPHRT_type) : longint
  1462.  
  1463.      Synopsis         This function returns the difference  in microseconds
  1464.                       between two TPHRT time stamps, which are generated by
  1465.                       calls  to  t_get.   t_diff and t_get  are  low  level
  1466.                       functions  that  are  of  interest primarily to users
  1467.                       building timer functions not implemented in TPHRT.
  1468.  
  1469.      Caveat           Don't pass the time stamps in the wrong order.
  1470.  
  1471.      See Also         t_get
  1472.  
  1473.  
  1474.      t_do_delay
  1475.  
  1476.  
  1477.      Purpose          Generates   a   precision  microsecond   delay   with
  1478.                       interrupts disabled
  1479.  
  1480.      Pascal           procedure t_do_delay(dp : tdelay_type)
  1481.  
  1482.      Synopsis         This function generates a precision microsecond delay
  1483.                       with interrupts disabled.   Using  this  function for
  1484.                       delays greater than 54925 microseconds will cause the
  1485.                       PC  clock to lose time.   Delay  parameters  of  type
  1486.                       tdelay_type for  the  delay  interval  desired    are
  1487.                       generated by t_ask_delay.
  1488.  
  1489.                       Delay interval error will be in the range  of  one to
  1490.                       three percent if t_calc_delay_ff is not used, zero to
  1491.                       one percent if it is.
  1492.  
  1493.      Caveat           Interrupts are disabled during the delay period
  1494.  
  1495.      See Also         t_ask_delay, t_calc_delay_ff, t_do_delay_wints
  1496.  
  1497.  
  1498.      t_do_delay_wints
  1499.  
  1500.  
  1501.      Purpose          Generates   a   precision  microsecond   delay   with
  1502.                       interrupts enabled
  1503.  
  1504.      Pascal           procedure t_do_delay_wints(dp : tdelay_type)
  1505.  
  1506.      Synopsis         This function is  identical to t_do_delay except that
  1507.                       interrupts are  enabled  during  the  delay interval.
  1508.                       This  will  introduce some additional  error  in  the
  1509.                       delay produced, but is more appropriate for  longer (
  1510.                       > 54925  usec)  delays.    Delay  parameters  of type
  1511.  
  1512.  
  1513.  
  1514.  
  1515.                                     TPHRT  20
  1516.  
  1517.  
  1518.  
  1519.  
  1520.  
  1521.                       tdelay_type for  the  delay  interval  desired    are
  1522.                       generated by t_ask_delay.
  1523.  
  1524.                       Delay interval error will be in the range  of  one to
  1525.                       three percent if t_calc_delay_ff is not used, zero to
  1526.                       one percent if it is.
  1527.  
  1528.      Caveat           Interrupt  activity  may  cause  random errors in the
  1529.                       delay interval produced.
  1530.  
  1531.      See Also         t_do_delay, t_ask_delay, t_calc_delay_ff
  1532.  
  1533.  
  1534.      t_entry
  1535.  
  1536.  
  1537.      Purpose          Starts the specified general purpose timer
  1538.  
  1539.      Pascal           procedure t_entry(timernum : integer)
  1540.  
  1541.      Synopsis         This   function   starts   a  general  purpose  timer
  1542.                       counting.  Timers are specified from 0 to  n-1  in C,
  1543.                       and from 1  to  n  in  Pascal.  The default number of
  1544.                       timers  is  10,  but that can be  modified  prior  to
  1545.                       calling t_start  by  passing  the  number  of  timers
  1546.                       needed to t_request.
  1547.  
  1548.                       Interrupts  are  normally  enabled  during  a  timing
  1549.                       interval.    t_setmode  can   be   used   to  disable
  1550.                       interrupts during any or all timing intervals.
  1551.  
  1552.      Caveat           No range checking is done.    NULL  pointer reference
  1553.                       possible if non-existant timer is started.
  1554.  
  1555.      See Also         t_exit, t_setmode
  1556.  
  1557.  
  1558.  
  1559.      t_exit
  1560.  
  1561.  
  1562.      Purpose          Stops the specified general purpose timer
  1563.  
  1564.      Pascal           procedure t_exit(timernum : integer)
  1565.  
  1566.      Synopsis         This function stops a general purpose timer counting.
  1567.                       Activation count and accumulated elapsed time for the
  1568.                       specified  timer  is  updated.   Timers are specified
  1569.                       from  0 to n-1 in C, and from 1 to n in Pascal.   The
  1570.                       default  number  of  timers is 10, but  that  can  be
  1571.                       modified  prior  to calling t_start  by  passing  the
  1572.                       number of timers needed to t_request.
  1573.  
  1574.      Caveat           No range checking is done.    NULL  pointer reference
  1575.                       possible if non-existant timer is started.
  1576.  
  1577.      See Also         t_entry
  1578.  
  1579.  
  1580.  
  1581.                                     TPHRT  21
  1582.  
  1583.  
  1584.  
  1585.  
  1586.  
  1587.      t_fname
  1588.  
  1589.  
  1590.      Purpose          Changes name of timer report file
  1591.  
  1592.      Pascal           procedure t_fname(fname : string)
  1593.  
  1594.      Synopsis         t_report can send its  output  to  a disk file, which
  1595.                       has the default name TIMER.TXT.  This function allows
  1596.                       the user to assign a different disk/path/file name to
  1597.                       this file.
  1598.  
  1599.      Caveat           No  checking  is  done  to  determine  if   the  file
  1600.                       description is valid.  Maximum  string  length  is 67
  1601.                       characters.
  1602.  
  1603.      See Also         t_rname, t_report
  1604.  
  1605.  
  1606.      t_get
  1607.  
  1608.  
  1609.      Purpose          Retrieves  a   high   resolution   time   stamp  with
  1610.                       interrupts enabled
  1611.  
  1612.      Pascal           procedure t_get(var timestamp : TPHRT_type)
  1613.  
  1614.      Synopsis         This function interrogates the  8253  timer  chip and
  1615.                       the low 16  bits  of  the  DOS time of day data words
  1616.                       fills  the passed TPHRT_type data structure with  the
  1617.                       microsecond  resolution  timestamp.    This   is  the
  1618.                       fundamental unit of time for TPHRT.  The elapsed time
  1619.                       between two TPHRT_type  time stamps may be determined
  1620.                       by t_diff.
  1621.  
  1622.      Caveat           Interrupts are enabled when t_get returns.
  1623.  
  1624.      See Also         t_hires_entry, t_hires_exit
  1625.  
  1626.  
  1627.      t_get_delay_ff
  1628.  
  1629.  
  1630.      Purpose          Retrieves the current delay calibration optimization
  1631.  
  1632.      Pascal           function t_get_delay_ff : real
  1633.  
  1634.      Synopsis         t_calc_delay_ff  calculates  and  installs  a   delay
  1635.                       calibration  optimization  for   a   specified  delay
  1636.                       interval length.  Using this  additional optimization
  1637.                       can  vastly  improve  the  TPHRT  delay  accuracy  in
  1638.                       critical  applications.    t_get_delay_ff returns the
  1639.                       current  delay  calibration optimization  in  effect.
  1640.                       The default value (i.e. - no additional optimization)
  1641.                       is 1.00.
  1642.  
  1643.      Caveat           None
  1644.  
  1645.  
  1646.  
  1647.                                     TPHRT  22
  1648.  
  1649.  
  1650.  
  1651.  
  1652.  
  1653.      See Also         t_calc_delay_ff, t_set_delay_ff
  1654.  
  1655.  
  1656.      t_hires_entry
  1657.  
  1658.  
  1659.      Purpose          Initiates timing with interrupts disabled
  1660.  
  1661.      Pascal           procedure t_hires_entry(var timestamp : TPHRT_type)
  1662.  
  1663.      Synopsis         This   function,   like   t_get,  retrieves  a  TPHRT
  1664.                       timestamp from the timing  hardware.    Unlike t_get,
  1665.                       t_hires_entry resets the 8253 timer  chip  to  0, and
  1666.                       interrupts are disabled at exit.  This  facilitates a
  1667.                       timing mode (set by  t_setmode)  that  functions with
  1668.                       interrupts disabled.
  1669.  
  1670.      Caveat           Since the 8253 is reset, only one timer may be active
  1671.                       at  any  one  time.  The timer will "roll over" after
  1672.                       54925  usec,  so  this  mode  is  suitable  for short
  1673.                       duration timing  only.  This is a low level function,
  1674.                       and is not meant to be called by the user.
  1675.  
  1676.      See Also         t_hires_exit, t_setmode
  1677.  
  1678.  
  1679.      t_hires_exit
  1680.  
  1681.  
  1682.      Purpose          Concludes a timing interval with interrupts disabled
  1683.  
  1684.      Pascal           procedure t_hires_exit(var timestamp : TPHRT_type)
  1685.  
  1686.      Synopsis         This  is the companion function to t_hires_entry  and
  1687.                       completes a timing interval with interrupts disabled.
  1688.                       At exit interrupts are enabled.
  1689.  
  1690.      Caveat           See t_hires_entry.
  1691.  
  1692.      See Also         t_hires_entry, t_setmode
  1693.  
  1694.  
  1695.      t_hook_int
  1696.  
  1697.  
  1698.      Purpose          Installs timers in the specified interrupt vector
  1699.  
  1700.      Pascal           procedure t_hook_int(int_no : integer)
  1701.  
  1702.      Synopsis         This  function  installs  timers  in   the  specified
  1703.                       interrupt  vector  to enable precise  timing  of  the
  1704.                       interrupt activity.
  1705.  
  1706.      Caveat           This is a low  level  function and is not meant to be
  1707.                       called by  the user.  Users wishing to understand how
  1708.                       TPHRT interrupt timing is accomplished should inspect
  1709.                       the source code to this routine.
  1710.  
  1711.  
  1712.  
  1713.                                     TPHRT  23
  1714.  
  1715.  
  1716.  
  1717.  
  1718.  
  1719.      See Also         t_unhook_int
  1720.  
  1721.  
  1722.      t_min_delay
  1723.  
  1724.  
  1725.      Purpose          Returns   minimum   delay   possible   in    run-time
  1726.                       environment
  1727.  
  1728.      Pascal           function t_min_delay : longint
  1729.  
  1730.      Synopsis         The minimum delay interval that can  be  generated by
  1731.                       t_do_delay  or t_do_delay_wints varies with the  run-
  1732.                       time hardware environment.  This function returns the
  1733.                       minimum  delay in microseconds that can be  generated
  1734.                       in the current environment.
  1735.  
  1736.      Caveat           None
  1737.  
  1738.      See Also         t_res_delay
  1739.  
  1740.  
  1741.      t_name
  1742.  
  1743.  
  1744.      Purpose          Associates a descriptive string with a generic timer
  1745.  
  1746.      Pascal           procedure  t_name(timerno  :  integer;  timername   :
  1747.                       tname)
  1748.  
  1749.      Synopsis         This  functions  assigns   a  string  of  maximum  20
  1750.                       characters to the specified generic timer number, and
  1751.                       this string  is  then  displayed  next  to  the timer
  1752.                       number in the timer report generated by t_report.
  1753.  
  1754.      Caveat           Maximum string length is 20 characters.
  1755.  
  1756.      See Also         None
  1757.  
  1758.  
  1759.      t_report
  1760.  
  1761.  
  1762.      Purpose          Generates a report of all generic timer activity
  1763.  
  1764.      Pascal           procedure t_report(whereto : integer)
  1765.  
  1766.      Synopsis         This  function  generates   a  report  of  all  timer
  1767.                       activity that was generated using t_entry and t_exit.
  1768.                       Parameter whereto specifies the report's destination:
  1769.                       0 sends the report to the CRT display, 1 sends  it to
  1770.                       a  disk file, and 2 sends it to  the  printer.    The
  1771.                       report  may  have  a  title  (see  t_rname),  and the
  1772.                       destination  disk   file   (if   used)   defaults  to
  1773.                       TIMER.TXT, but this can modified (see t_fname).
  1774.  
  1775.  
  1776.  
  1777.  
  1778.  
  1779.                                     TPHRT  24
  1780.  
  1781.  
  1782.  
  1783.  
  1784.  
  1785.                       Timer  reports  have   two  formats,  and  these  are
  1786.                       selected by t_set_report.   The HIGHWATER report type
  1787.                       shows  the  activity  of  all timers, including those
  1788.                       with zero activation counts, up to the highest number
  1789.                       timer activated.  The NONZERO report type  only shows
  1790.                       timers with nonzero activation counts.
  1791.  
  1792.      Caveat           None
  1793.  
  1794.      See Also         t_rname, t_fname, t_set_report
  1795.  
  1796.  
  1797.      t_request
  1798.  
  1799.  
  1800.      Purpose          Request specific number of generic timers
  1801.  
  1802.      Pascal           procedure t_request(numtimer : integer)
  1803.  
  1804.      Synopsis         t_request  provides  a  mechanism  to   override  the
  1805.                       default   number  of  generic  timers  allocated   by
  1806.                       t_start.  If the user requires more (or less) than 10
  1807.                       timers,   the  number  required  may  be  passed   to
  1808.                       t_request, and t_start  will attempt to allocate this
  1809.                       number of timers.
  1810.  
  1811.      Caveat           Call before t_start.
  1812.  
  1813.      See Also         t_start
  1814.  
  1815.  
  1816.      t_res_delay
  1817.  
  1818.  
  1819.      Purpose          Retrieves delay resolution of run-time environment
  1820.  
  1821.      Pascal           function t_res_delay : longint
  1822.  
  1823.      Synopsis         In slower hardware environments, the delay resolution
  1824.                       of t_do_delay  and  t_do_delay_wints  may  be several
  1825.                       microseconds.   This  function  returns  the run-time
  1826.                       delay resolution in units of tenths of a microsecond.
  1827.                       For example, if t_res_delay returns  a  value  of 44,
  1828.                       that means the delay  functions  can  generate delays
  1829.                       starting  at   their   minimum   delay   length  (see
  1830.                       t_min_delay)   and   up    in   increments   of   4.4
  1831.                       microseconds.
  1832.  
  1833.      Caveat           None
  1834.  
  1835.      See Also         t_min_delay
  1836.  
  1837.  
  1838.      t_reset
  1839.  
  1840.  
  1841.      Purpose          Resets one or all generic timers
  1842.  
  1843.  
  1844.  
  1845.                                     TPHRT  25
  1846.  
  1847.  
  1848.  
  1849.  
  1850.  
  1851.      Pascal           procedure t_reset(timernum : integer)
  1852.  
  1853.      Synopsis         This  function  zeros  the accumulated activation and
  1854.                       elapsed timer counts for  a  specified  timer  in the
  1855.                       range of 0  to  n-1 in C, or 1 to n in Pascal.  If -1
  1856.                       is passed, all generic timers are reset.
  1857.  
  1858.      Caveat           No range checking is done.  Null pointer reference is
  1859.                       possible if a non-existant timer is specified.
  1860.  
  1861.      See Also         t_ask_timer
  1862.  
  1863.  
  1864.      t_resume
  1865.  
  1866.  
  1867.      Purpose          Resumes a suspended generic timer
  1868.  
  1869.      Pascal           procedure t_resume(tnum : integer)
  1870.  
  1871.      Synopsis         Functions t_suspend and t_resume  allow  the  user to
  1872.                       stop and restart an active timer without incrementing
  1873.                       its activation count.
  1874.  
  1875.      Caveat           No range checking is done.  NULL pointer reference is
  1876.                       possible if a non-existant timer is specified.
  1877.  
  1878.      See Also         t_suspend
  1879.  
  1880.  
  1881.      t_rname
  1882.  
  1883.  
  1884.      Purpose          Assigns a title to the timer report
  1885.  
  1886.      Pascal           procedure t_rname(report_title : string)
  1887.  
  1888.      Synopsis         The  generic  timer  report  generated   by  t_report
  1889.                       contains   a   horizontally   centered  title,  which
  1890.                       defaults to Timer Summary.  This function  allows the
  1891.                       user to specify an alternate title.
  1892.  
  1893.      Caveat           Max string length is 80 characters.
  1894.  
  1895.      See Also         t_report, t_fname
  1896.  
  1897.  
  1898.      t_set_delay_ff
  1899.  
  1900.  
  1901.      Purpose          Sets delay calibration optimization
  1902.  
  1903.      Pascal           procedure t_set_delay_ff(delay_ff : real)
  1904.  
  1905.      Synopsis         This function allows the  user  to  set the new delay
  1906.                       calibration  optimization  for  use  by  t_ask_delay.
  1907.                       Delay  calibration optimization  for  a  given  delay
  1908.  
  1909.  
  1910.  
  1911.                                     TPHRT  26
  1912.  
  1913.  
  1914.  
  1915.  
  1916.  
  1917.                       interval  can be automatically calculated and set  by
  1918.                       t_calc_delay_ff.  Calling t_set_delay_ff with a value
  1919.                       of  1.00  removes  any delay calibration optimization
  1920.                       that was in effect.
  1921.  
  1922.      Caveat           None
  1923.  
  1924.      See Also         t_calc_delay_ff, t_get_delay_ff, t_ask_delay
  1925.  
  1926.  
  1927.      t_setmode
  1928.  
  1929.  
  1930.      Purpose          Sets generic timing mode
  1931.  
  1932.      Pascal           procedure t_setmode(modetype : integer)
  1933.  
  1934.      Synopsis         Two modes of generic  timing  are  available: INTS_ON
  1935.                       enables generic timing  using t_entry and t_exit with
  1936.                       interrupts  enabled,  and  this  is the default mode.
  1937.                       NO_INTS_ON enables timing  with  interrupts disabled,
  1938.                       and this mode  is particularly suitable for extremely
  1939.                       short  duration  timing  that   may   be   skewed  by
  1940.                       background interrupt activity.   In  this  mode, only
  1941.                       one timer may be active at any time,  and  each timer
  1942.                       will   "roll   over"   after  54925  microseconds  of
  1943.                       continuous activation.
  1944.  
  1945.                       As long as only one timer is active at once,  the two
  1946.                       timer modes may be freely  mixed.  In order to change
  1947.                       modes, call t_setmode with the desired mode  prior to
  1948.                       calling the t_entry/t_exit functions.
  1949.  
  1950.      Caveat           NO_INTS_ON  mode  is  not  compatible  with  multiple
  1951.                       active timers or BIOS interrupt timing.
  1952.  
  1953.      See Also         None
  1954.  
  1955.  
  1956.      t_start
  1957.  
  1958.  
  1959.      Purpose          Initializes TPHRT timing functions
  1960.  
  1961.      Pascal           procedure t_start
  1962.  
  1963.      Synopsis         This function  initializes  the  entire  TPHRT timing
  1964.                       system, and must  be  called prior to any other TPHRT
  1965.                       functions with the  exception  of  t_request.    If a
  1966.                       different  number  of  timers  other than the default
  1967.                       number provided (10) is required, t_request should be
  1968.                       called prior to t_start to specify the number needed.
  1969.                       In C,  if t_start can allocate enough heap to fulfill
  1970.                       the timer  request,  it  will  do  so,  calibrate the
  1971.                       timing  system,  and  return  TRUE.    If  the memory
  1972.                       request  fails,  it  will  return  FALSE.    In Turbo
  1973.                       Pascal, memory allocation failure  will  result  in a
  1974.  
  1975.  
  1976.  
  1977.                                     TPHRT  27
  1978.  
  1979.  
  1980.  
  1981.  
  1982.  
  1983.                       run-time error.  Each timer requires approximately 35
  1984.                       bytes of heap.
  1985.  
  1986.                       The 8253 timer chip is set to mode 2.
  1987.  
  1988.      Caveat           None
  1989.  
  1990.      See Also         t_request, t_stop
  1991.  
  1992.  
  1993.      t_stop
  1994.  
  1995.  
  1996.      Purpose          Shuts down TPHRT timing logic
  1997.  
  1998.      Pascal           procedure t_stop
  1999.  
  2000.      Synopsis         This  function  deallocates  all heap associated with
  2001.                       generic timers and restores the  8253  timer  chip to
  2002.                       mode 3.  It must be called prior to program exit, and
  2003.                       no TPHRT calls (except t_request) are valid without a
  2004.                       call to t_start to reinitialize the timing system.
  2005.  
  2006.      Caveat           None
  2007.  
  2008.      See Also         t_start, t_request
  2009.  
  2010.  
  2011.      t_suspend
  2012.  
  2013.  
  2014.      Purpose          Suspends an active generic timer
  2015.  
  2016.      Pascal           procedure t_suspend(tnum : integer)
  2017.  
  2018.      Synopsis         Functions t_suspend and t_resume  allow  the  user to
  2019.                       stop and restart an active timer without incrementing
  2020.                       its activation count.
  2021.  
  2022.      Caveat           No range checking is done.  NULL pointer reference is
  2023.                       possible if a non-existant timer is specified.
  2024.  
  2025.      See Also         t_resume
  2026.  
  2027.  
  2028.      t_unhook_int
  2029.  
  2030.  
  2031.      Purpose          Removes timers from the specified interrupt vector
  2032.  
  2033.      Pascal           procedure t_unhook_int(int_no : integer)
  2034.  
  2035.      Synopsis         This  function  removes  timers  from  the  specified
  2036.                       interrupt  vector  to  disable  precise timing of the
  2037.                       interrupt activity.
  2038.  
  2039.  
  2040.  
  2041.  
  2042.  
  2043.                                     TPHRT  28
  2044.  
  2045.  
  2046.  
  2047.  
  2048.  
  2049.      Caveat           This is a low  level  function and is not meant to be
  2050.                       called by  the user.  Users wishing to understand how
  2051.                       TPHRT interrupt timing is  accomplished  may  want to
  2052.                       inspect the source code to this routine.
  2053.  
  2054.      See Also         t_hook_int
  2055.  
  2056.  
  2057.  
  2058.  
  2059.  
  2060.  
  2061.  
  2062.  
  2063.  
  2064.  
  2065.  
  2066.  
  2067.  
  2068.  
  2069.  
  2070.  
  2071.  
  2072.  
  2073.  
  2074.  
  2075.  
  2076.  
  2077.  
  2078.  
  2079.  
  2080.  
  2081.  
  2082.  
  2083.  
  2084.  
  2085.  
  2086.  
  2087.  
  2088.  
  2089.  
  2090.  
  2091.  
  2092.  
  2093.  
  2094.  
  2095.  
  2096.  
  2097.  
  2098.  
  2099.  
  2100.  
  2101.  
  2102.  
  2103.  
  2104.  
  2105.  
  2106.  
  2107.  
  2108.  
  2109.                                     TPHRT  29
  2110.  
  2111.  
  2112.  
  2113.  
  2114.  
  2115.                             TPHRT V3.00 Registration
  2116.  
  2117.  
  2118.      Name ______________________________ Company ______________________________
  2119.  
  2120.      Address __________________________________________________________________
  2121.  
  2122.      City/State/Zip ___________________________________________________________
  2123.  
  2124.      Telephone _______________________ Got TPHRT from _________________________
  2125.  
  2126.      Version 3 Single Language Timer Toolboxes.  Includes large & small
  2127.      model libraries (C), full library source, support by US Mail or
  2128.      Compuserve Email.  License does not permit commercial distribution
  2129.      of object code.
  2130.  
  2131.      Qty _____ TPHRT V3 for Turbo Pascal 5 & 5.5 @ $20.00 each ........ _______
  2132.  
  2133.      Qty _____ TCHRT V3 for Turbo C @ $20.00 each ..................... _______
  2134.  
  2135.      Qty _____ MSCHRT V3 for Microsoft C @ $20.00 each ................ _______
  2136.  
  2137.      Version 4 Timer  Toolbox. Supports  TC & MSC in small, medium,
  2138.      compact, and large models, Turbo Pascal 5 & 5.5.  20 additional
  2139.      functions to manage timers, profile interrupts, generate synchronous
  2140.      alarms, run the timer tick interrupt at a user specified rate.
  2141.      Two standalone utilities time execution and profile interrupts of
  2142.      most executable programs without recompilation.  Full library
  2143.      source in C & Pascal included.  Printed manual.  Support by
  2144.      telephone, US Mail or Compuserv Email.  License  permits
  2145.      commercial distribution of object code.
  2146.  
  2147.      Qty ______ PCHRT V4.00 @ $49.95 each ............................. _______
  2148.  
  2149.      Shipping in USA @ $2.00 .......................................... _______
  2150.  
  2151.      Shipping outside USA @ $4.00 ..................................... _______
  2152.  
  2153.      Subtotal ......................................................... _______
  2154.  
  2155.      Michigan residents add 4% ........................................ _______
  2156.  
  2157.      Total enclosed ................................................... _______
  2158.  
  2159.  
  2160.      Payment method:  ___Check  ___Money Order  ___VISA  ___MasterCard
  2161.  
  2162.      Card # ____________________________________________ Exp _________
  2163.  
  2164.      Signature _________________________________________
  2165.  
  2166.      Remit to Ryle Design, P.O. Box 22, Mt. Pleasant, MI 48804
  2167.  
  2168.      Credit  card  customers  may  order  by  Email  on Compuserve  to
  2169.      73047,1765,  or  by telephone at (517) 773-0587.  This is a voice
  2170.      mail system.  Leave your name and number in voice mailbox #2, and
  2171.      your call will be returned and your order taken.
  2172.  
  2173.      Thank you!
  2174.  
  2175.                                     TPHRT  30
  2176.